home *** CD-ROM | disk | FTP | other *** search
-
-
- AMenu v1.3 (Anthony's Menu) Documentation
-
-
- AMenu is a complete reprogramed version of Darin Johnson's
- `MyMenu v1.0' from `Fish Disk 225'. Its purpose is to attach extra
- menus to the workbench menus and execute commands when selected.
-
- The original program `MyMenu' had a number of problems. Commands
- run in the CLI always had a current directory of the boot device and
- failed if no disk is present in that device. Also the stack size for
- the commands was fixed to 4000 bytes, too small for many such
- commands. Further more, if any program changes the Preferances of
- the workbench (Programs such as Preferences, AudioMaster, and many
- WordProcesses), the extra menus will be disconnected and need to be
- reattached by manually restarting MyMenu to continue their use. Also
- MyMenu required the Tool of a Project that was run in WB mode to
- have an attached icon.
-
- AMenu solves all these problems. The default current directory
- for CLI type commands is now selectable and defaults to the assigned
- `SYS:' directory rather than the boot device. Commands can also have
- their current directory, run prioity and stack size individually
- set. Commands can also be run with a console which will accept input
- as well as ouput to/from the command.
- Titles or comment items can also be added to the menus, and more
- style and coloring options are available and spacing between menus
- can also be adjusted to the users desire.
- The format for AMenu's script file is greatly different to that
- of MyMenu. Instead a structured format is used simular to another
- MyMenu derivative, `ParM' (Fish Disk 375). This format allows the
- addition of columned menus to AMenu and the ability to modify the
- style of a sub-menu after the head item of the sub-menu is given.
- AMenu performes more extensive error checking than MyMenu in both
- the reading of the configuration file and in the command execution
- making it easier on the user to debug his menus. MyMenu often just
- does nothing on an error, leaving the user in the dark.
- To top all this off, the size of the AMenu-Handler (the resident
- controlling program) is smaller than that of the MyMenu-Handler!
- ( AMenu-Handler - 4780 bytes vs. MyMenu-Handler - 5412 bytes )
-
- I renamed MyMenu to AMenu so as to avoid any confusion in thier
- config files which are incompatable and to differentate my version
- from any future releases he may care to make. (Apology to Darin)
-
-
- Installation:
-
- NOTE: The "ARP.Library" (version 35 or greater) must be installed
- in the "L:" directory. AMenu does not directly require the "Run"
- command in "C:" as did MyMenu.
-
- Copy "AMenu-Handler" to the "L:" directory. AMenu will also look
- for this file in the current directory if it does not exist in the
- "L:" directory.
-
- Simularity the file "AMenu.Config" should be in the "S:". If not
- present, AMenu will also look in the current directory.
-
- If you already have a "MyMenu.Conf" in your "S:" directory,
- rename it "AMenu.Config", and then edit it to convert any `CLI'
- command execution mode to the AMenu's equivelent mode `RB'
- (RunBack). After that it is a matter of grouping items in the same
- menu together and changing the structure to the format given in the
- sample config file, and this manual.
-
-
- Running:
-
- Syntax :
- AMenu [quit]
-
- The command "AMenu" will load and start up the handler process.
- Or if already running, it will re-parse the configuration file.
-
- The quit argument will remove AMenu, and has been throughly
- checked for memory leaks. MyMenu does have a leak of about 40
- bytes. ASIDE: It seems almost all Manx pograms have this leak.
-
-
- Configuration file:
-
- "AMenu.Config" is stored in the "S:" directory but is also looked
- for in the current directory.
-
- If any names used in the config file contain white space or non
- alpha-numeric characters they should be quoted, a single word name
- however does not need quotes.
-
- Example:
- "SubMenu ->"
-
- A Comment can appear almost anywhere in the command file. The
- only axception is after the name of a command to execute is given in
- an ITEM statement. In this case the comment would be thought to be
- part of the arguments to the command itself and executed when the
- command is executed. A comment is prefaced with a `#' character and
- then everything from there, up to and including the end of line.
-
- Example:
- # This is a comment is ignored by AMenu as a Comment!
-
-
- COLOR fore back - Text Color ( default is black on white ( 2 1 ) )
- TCOLOR fore back - Title Color ( default is black on orange ( 2 3 ) )
-
- These statements define the colors to use in the creation of
- the MenuItems that follow. COLOR is used for command items while
- TCOLOR is the coloring of menu titles (Menu Comments).
- Note:- The Menus use the same general background color as
- workbench and thus the default colors for TITLE's is really, black
- text on orange background on a white menu.
-
-
- STYLE COMP - highlight menu items by inverting colors (Default)
- STYLE BOX - highlight by drawing a box around them.
-
- Select the style to use in highlighting menu items that follow.
- After the STYLE statement either BOX or COMP must be given. This
- is only used for command items and sub-menu names. Menu titles
- contain no highlighting as they perform no action when selected.
-
-
- MENUGAP n - Gap between menus (default as per workbench menus )
-
- This command defines the amount of space (in characters) to add
- when creating a new menu. The value is only used when a new menu
- name is given in the MENU command intailing the creation of
- another menu.
- To have the menus as close togetter as possible use a value of
- 1. If the value is too big, menus may overflow the screen which
- AMenu will warn you about but will continue regardless.
-
-
- DIRECTORY full-dir-path ( Default "Sys:" )
-
- This statement defines the default current directory to use to
- find and execute commands. If this command is not given the
- current directory defaults to the assigned "Sys:" directory (Not
- the Boot device (DF0:) as MyMenu does). It should be defined only
- once in a file and if multiply defined only the last will be used.
- The DIR command-modifier works from this directory path, so you
- need not give a full pathname to individual commands (using less
- memory to store).
-
-
- CONSOLE console-name ( Default "CON:100/11/200/20/AMenu Command" )
-
- This sets the name of the console to use for commands with the
- execution-mode CLI. This can be changed on an individual basis using
- the CON command modifier. As with DIRECTORY only one of these should be
- given if at all. If more than one is fould only the last will be used.
-
-
- MENU [COLUMNS n] menu-name
- ENDMENU
- SUBMENU [COLUMNS n] submenu-name
- ENDSUBMENU
-
- These statements define the overall menu structure. The COLUMNS
- option is a new feature which allows the user to define the number of
- columns the menu is to spread its element over. If COLUMNS is not given
- it defaults to the normal value of one column. Items in a menu are
- arranged in column order as showen in the figure below.
- A SUBMENU command must occur within a MENU structure and under
- the current scheme of intuition, you are not allowed a
- "SUBSUBMENU" within a SUBMENU.
- The ENDMENU statement is actually not needed as another MENU
- statement (or end of file) following implys the end of the previous
- menu. The same is true for ENDSUBMENU but is required if more items
- follow in the surrounding MENU structure (as in the figure below).
- _________________________________________________________
- ________|_Menu_|_________________________________________
- | Title Item 5 |
- | Item 1 Item 6 _|___________________
- | Item 2 SubMenu| Sub 1 Sub 3 Sub 4 |
- | Item 3 Item 7 |_Sub_2_________Sub_5_|
- |__Item_4____________| ^.
- Space left by SKIP!
- Figure: a 2 column menu with 3 column sub-menu.
-
-
- TITLE title-name
- SKIP
- ITEM item-name [<char>] | exec-mode [modifiers] command command-args
-
- These three elements and any SubMenu names form the contents of
- any particular menu. They are added to the current menu in the
- order given in columns. The number of elements stored in each
- column is decided by AMenu by dividing the number of elements
- given in a particular menu by the number of columns that menu has
- and can be adjusted using SKIP statements. (See SKIP below).
-
- The TITLE element defines an menu item which is a comment.
- Selecting this item does nothing. In fact it will not even
- highlight when the mouse is over it. A collection of these could
- be used to make a type of menu note about something. The coloring
- for this element is defined with the TCOLOR statement and is often
- used to make a title standout from the normal ITEM's. They are
- most commonly used at the top of the first column but can appear
- anywhere.
-
- SKIP is used to leave gaps in the menu structure, or to insure
- AMenu correctly arranges the elements in the appropiate columns.
- It up no memory as it doesn't add any new menu elements to the
- menu. IE no cost. WARNING: Skip'ed space on the edge or bottom of
- a menu may be removed automatically by the intuition menu display
- routines and thus ignored in the final display of the menu. If
- you really want the space on the edge of the menu use a TITLE
- element with TColor set to 1 1 (white text on a white background
- on a white menu) to make it invisible.
-
- ITEM define the actual job of AMenu. When such a element is
- selected the command given is run in background using one of three
- styles of execution.
- The optional <char> is used as a menu key shortcut by pressing
- the Right-Amiga key and that letter. It must be surrounded by <>'s
- if given. NOTE: This also adds a Amiga-letter symbol to the
- displayed menu element.
-
- The vertical bar `|' is used to seperate the menu definition
- from the command definition. Following this is one of three
- exec-modes notifing AMenu the method in with the command is to be
- run.
-
- RB or RUNBACK
- - the command is executed in "RunBack" or "ARun NOIO"
- style. This is equivelent (but not same as) the CLI
- command execution mode used in MyMenu. No console is
- provided and any output will be lost.
-
- CLI - a console is opened for the command to output to or
- recieve input from. The console will automatically
- close on the command exit. and can be defined using
- the CONSOLE command globally or using the CON
- modifer locally (See below). (New to AMenu)
-
- SCR or SCRIPT
- - This is equivelent to the command `NewCLI' or
- `AShell'. This starts a new shell window, with the
- command given being used as a `FROM' script file. If
- the script does not end in a `EndCLI' command the
- console will then become an interactive shell
- window. A good script to use is "S:Shell-Startup"
- which will start a normal shell window.
-
- WB - The command is run as if started from the Workbench
- As from AMenu v1.3 this command has been fixed so
- that it works correctly for projects (as if just the
- project was double-clicked) as well as tools. It
- does this in a way that also avoids a bug in the
- lattice C startup code (See WBTests.txt).
-
-
- The following modifiers allow the user to change the way the
- environment is set up when this command is executed. Zero or more
- the following can be used :-
-
- PRI prioity-number ( All modes )
- Sets the prioity to somthing other 0 the default
- prioity. Eg: -20 will run only if nothing else
- does. This is to be used with caution as a bad
- prioity could cause problems on the system. I
- suggest you only use the range -20 to 5.
-
- STK stack-size ( All Modes )
- This uses a different stack size for the command
- other than the default size of 4096. For WB mode the
- stack is set to this ONLY if the stack setting in
- the icon executed is less than this or non-existant.
- IE: the larger of the two is used for the tool.
-
- DIR dir-path ( Any Mode but WB )
- Use this dir-path as the current directory for the
- command. This path is from the default directory
- given with the DIRECTORY command above. The current
- directory for WB programs is that of the tool
- executed.
-
- CON console-name ( CLI and SCR modes only )
- Use a different console window, for this particular
- command or script than that set with the CONSOLE
- command above.
-
- After these options the command name wust be given. After the
- command is given the rest of the line is treated as arguments to
- that command. NOTE:- WB and SCR modes ignores these arguments
- completely.
-
-
- Examples:
-
- Item "JrComm" | WB Sys:Tools/Comms/JrComm
-
- Executes the command "JrComm", stored in the directory
- "Sys:Tools/Comms", using the current defaults, and executed as if
- started by workbench.
-
- SubMenu "AMenu ->"
- Title " AMenu "
- Item "Rebuild" | RB Dir Utilities AMenu
- Item " QUIT " | RB Dir Utilities AMenu quit
- EndSubMenu
-
- Defines a sub-menu with a title to execute the command "AMenu"
- stored in the directory "Utilities" off the default directory
- (probably SYS: is not set) with different arguments.
- NOTE: This is segested way to execute AMenu from itself. It
- assumes that the "AMenu.Config" file is stored either in the "S:"
- directory where it should be or in the "Utilities" directory (the
- current directory for command).
-
-
- Other Notes on Config:
-
- The case of all Statements words used in AMenu is ignored. While
- the case for names is recored literally.
-
- Line breaks can occur at any time in any statement and is treated
- as normal white space. The ITEM command is no different in this
- respect until the command name is given. After the command name, ALL
- TEXT until the end of line is treated as the commands argument and
- as such can't be broken by newline characters, nor should it contain
- a comment.
-
- Line Breaks are ok in the following :
- ITEM Archologist
- | RB DIR NetHack:
- STK 8000
- NetHack -A -u Archie
-
- Illegal Line break in this menu command :
- ITEM Archologist | RB DIR NetHack: Stk 8000 NetHack -A
- -u Archie
-
- AMenu uses the "AmigaDOS Replacment Project" or ARP Library. In
- particular it uses "ASynchRun()" function rather than the AmigaDOS
- "Execute()" to execute CLI and RB commands. This function will NOT
- execute scripts directly (reporting an error to that effect). To
- execute a script use the following method. Note however that the
- script should end in "EndCLI" to close the window.
-
- ITEM ExecuteScript | RB NewCLI con: FROM script-file
-
-
- Re-Compiling:
-
- Version 1.1 of AMenu (unreleased) was a complete reprogram of
- MyMenu v1.0. I added all the new commands above but retained the
- orignal single "MENU" statement for all menu elements.
-
- AMenu v1.2 only reprogramed the files "Parse.c" and "Menu.c" to
- add structuring statements and remove the named searches of menus
- already created. This simplified "Menu.c" and allowed the addition
- of columns, recursive menu positioning, and the ability to change
- menu style between the declaration of a SubMenu and the first
- element in the submenu.
-
- For "AMenu-Handler", I use a C startup file "_main.c" rather than
- "lib:c.o". I did this as AMenu-Handler is a Process, but, must not
- wait for a nonexistant WBStartup message. Also "lib:c.o" is very
- large, 1136 bytes, while "_main.o" is only 164 bytes. A considerable
- difference in size (and memory usage).
-
- Version 1.3 is a rewrite of the Workbench startup code to stop some
- annoying bugs and the addition of my "ArpC" Arp library startup code.
-
-
- Limitations, bugs, and other wierd things:
-
- The search path for commands is only the current dir (set with
- DIR or the default DIRECTORY) and the "C:" directory. I do not
- at this time intend expanding this path. Though I do know how to
- do so.
-
-
- Acknowledgements:
-
- by Darin Johnson
- Matt Dillon - Ideas for menu building and how to load in the
- handler were taken from DME and DMouse.
- Peter da Silva - Ideas taken from wblaunch program.
- Rob Peck - Some ideas and help.
- Davide Cervone - LOTS of ideas taken from MonIDCMP.
-
- by Anthony Thyssen
- Darin Johnson - for MyMenu the best command menu program (until now)
- Doug Walker - C startup methond used in "_main.c" for AMenu-Handler
- and ArpC startup code for ARP programs.
- ARP Team - for ARP, Prog. Guild, and ARun as an example
- Sylvain Rougier & Pierre Carrette
- - auther of ParM for structured menu style
- NOTE:- Much of the code from ParM v1.3 was taken from MyMenu but these
- pirates (no offence) make no mention of this fact, thus claiming it
- is all their own work. They should have done so. (In a latter release
- of ParM SR & PC did make small mention in their programs history)
-
-
- Signature:
-
- Anthony Thyssen (Dragon Computing),
- co/ Commodore Computer Users Group (Qld) Inc.
- P.O. Box 274, Springwood, Qld., Australia, 4127
-
- Beware, The light at the end of the tunnel may be a oncoming dragon!
-
-